@h2loop/uav 1.2.0 → 1.2.2

package/README.md

@@ -59,7 +59,9 @@ skills/uav/             # on-demand `uav` skill + references
 data/                   # bundled apm-params.json + built-in defaults
 bridge/                 # optional MAVLink→MCP Python bridge
 plugins/                # BUILT bundle (index.js + worker/) — generated
-mcp.json                # exa + mavlink MCP servers (disabled by default)
+mcp.json                # exa MCP server (disabled by default); mavlink is registered
+                        #   from src/index.ts's config hook — it needs a resolved
+                        #   interpreter + an ABSOLUTE script path, which static JSON can't give
 ```
 
 ## Run standalone
@@ -235,30 +237,29 @@ project KG.
 
 A local Python stdio server. Read-only tools: `read_params`, `param_get`, `param_get_all`,
 `get_messages`, `tail_telemetry`, `get_flight_mode`, `get_status`. The write tier
-(`param_set` / `param_set_batch`) is **off by default** — see below.
+(`param_set` / `param_set_batch`) is **on by default** so tune→push→retest works out of the
+box — see below.
 
 **Requires:**
-- Python ≥ 3.10 with `pymavlink>=2.4.49` and `mcp[cli]>=1.0.0` installed. The pack does **not**
+- Python ≥ 3.10 with `pymavlink>=2.4.49` and `mcp[cli]>=1.0.0,<2` installed. The pack does **not**
   auto-provision a venv — install the deps yourself: `pip install -r bridge/requirements.txt`
   (ideally into a venv), and point the command's `python3` at that interpreter.
 - A reachable MAVLink endpoint (e.g. `udp:127.0.0.1:14550` from SITL or a telemetry radio),
   or a `.tlog`/`.log` file for offline replay.
 - The `bridge/` directory ships with the plugin (the `mcp.json` references it).
 
-Enable per-project in your Hydron config. **Param writes are OFF by default** (the bridge
-defaults to `--read-only`). To enable the tune→push→retest write tier, the command must pass
-**both** `--no-read-only` **and** `--allow-param-write`. ⚠ this lets the agent write params to
-a **live vehicle** — prefer SITL/bench.
-```jsonc
-"mcp": {
-  "mavlink": {
-    "enabled": true,
-    "command": ["python3", "<plugin-path>/bridge/uav_mavlink_bridge.py",
-                "--connect", "udp:127.0.0.1:14550",
-                "--no-read-only", "--allow-param-write"]
-  }
-}
+Ships **enabled**, with param writes **on** — the command passes `--no-read-only`
+`--allow-param-write`, so `param_set` / `param_set_batch` are registered and the tuning loop
+works with no configuration. ⚠ this lets the agent write params to a **live vehicle** — prefer
+SITL/bench. To ship read-only, drop both flags.
+
+No `--connect` is passed, so the target comes from the **`MAVLINK_CONNECT`** env var, falling
+back to `udp:127.0.0.1:14550`:
+```bash
+export MAVLINK_CONNECT=serial:/dev/ttyUSB0:57600      # COM3:57600 on Windows
 ```
+Don't put it in the server's `environment` block — Hydron spreads that *over* `process.env`, so
+it would shadow your export instead of defaulting to it.
 
 Connect-target forms: `udp:HOST:PORT` (default `udp:127.0.0.1:14550` = SITL/MAVProxy) |
 `tcp:HOST:PORT` | `serial:/dev/ttyUSB0:BAUD` | `/path/log.tlog` (offline replay); can also be

package/USAGE.md

@@ -12,7 +12,7 @@ covers getting it running on **macOS, Linux, and Windows**, validating it works,
 - **Bun** — *only* needed to build the bundle from source or run the pack's tests; **not**
   needed to use a published pack.
 - **Python ≥ 3.10** — *only* for the optional live MAVLink bridge (`pymavlink>=2.4.49` +
-  `mcp[cli]>=1.0.0`). The pack does **not** auto-provision a venv; you install the deps
+  `mcp[cli]>=1.0.0,<2`). The pack does **not** auto-provision a venv; you install the deps
   yourself (see §6). Plain `.bin` log analysis needs no Python.
 - *Optional:* `export EXA_API_KEY=…` for web grounding of bounds.
 - **macOS, Linux, and Windows are all native** — no WSL required. The pack resolves the Python
@@ -127,50 +127,67 @@ See `skills/uav/references/project-config.md` for the full list (`uav-thresholds
 A **MAVLink→MCP bridge**: a local Python stdio server Hydron spawns so the agent can query a
 live vehicle / SITL / log replay. Read-only tools: `get_status`, `get_flight_mode`,
 `read_params`, `param_get`, `param_get_all`, `get_messages`, `tail_telemetry`. The **write**
-tools `param_set`/`param_set_batch` are **off by default** (see the ⚠ note below).
+tools `param_set`/`param_set_batch` are **on by default**, so tune→push→retest works out of
+the box (see the ⚠ note below to turn them off).
 
-### Install the Python deps yourself
+### Install the Python deps (the only manual step)
 The pack does **not** auto-provision a venv. The bridge needs Python ≥ 3.10 with
-`pymavlink>=2.4.49` and `mcp[cli]>=1.0.0`:
+`pymavlink>=2.4.49` and `mcp[cli]>=1.0.0,<2`:
 ```bash
 pip install -r bridge/requirements.txt     # ideally into a venv
 ```
-Then point the `mavlink` command's first element at that interpreter. **This is the one place
-the interpreter is not auto-detected** — `mcp.json` is static config that Hydron spawns
-directly, so it ships the POSIX default `python3`. On Windows change it to `python` (or the
-venv's full `…\Scripts\python.exe`); everywhere else an absolute venv path is the safest value.
-
-### Enable and configure (per-project in opencode.jsonc)
-The `mavlink` server ships in `mcp.json` **disabled by default**. Enable it per-project:
-```jsonc
-"mcp": {
-  "mavlink": {
-    "enabled": true,
-    "command": ["python3", "<plugin-path>/bridge/uav_mavlink_bridge.py",
-                "--connect", "udp:127.0.0.1:14550"]
-  }
-}
+> The `<2` bound is required, not cosmetic: the MCP Python SDK **removed `mcp.server.fastmcp`
+> in 2.x**, so the bridge fails at import on `mcp>=2`. Verified working on 1.29.0.
+
+You do **not** need to edit any command. The plugin registers the `mavlink` server itself at
+startup, resolving:
+
+- **the interpreter** — via the same probe-by-execution resolver the `.tlog`/`.ulog` decoders
+  use, so `python3` / `python` / the Windows `py -3` launcher are all handled and Windows'
+  Microsoft-Store alias stubs are rejected. Pin a specific one with `UAV_PYTHON` (e.g. a venv:
+  `export UAV_PYTHON=/path/.venv/bin/python`, or `…\Scripts\python.exe` on Windows).
+- **the script path** — absolute, inside the installed plugin bundle. This matters: Hydron
+  spawns local MCP servers with the cwd set to *your project*, so a bundle-relative path can
+  never resolve. That is why the server is no longer declared in `mcp.json`.
+
+If no usable Python is found the server is not registered at all; if Python is found but can't
+`import mcp, pymavlink`, it is registered **disabled** — so you see it listed rather than
+getting a failed server on every launch. Check with `hydron mcp list`.
+
+### Point it at your vehicle
+The `mavlink` server is registered **enabled**, with param writes on, so nothing needs enabling.
+The one thing you may need to change is the connect target.
+
+The command passes **no** `--connect`, so the bridge falls back to its own default —
+which reads the **`MAVLINK_CONNECT`** environment variable, then `udp:127.0.0.1:14550`. So for
+anything other than local SITL/MAVProxy, just export the target:
+```bash
+export MAVLINK_CONNECT=serial:/dev/ttyUSB0:57600      # or COM3:57600 on Windows
 ```
 Connect-target forms: `udp:HOST:PORT` (default `udp:127.0.0.1:14550` = SITL/MAVProxy) |
 `tcp:HOST:PORT` | `serial:/dev/ttyUSB0:BAUD` (on Windows a COM port, e.g. `COM3` or
-`COM3:57600`) | `/path/log.tlog` (offline replay). Can also be set via the `MAVLINK_CONNECT`
-env on the server.
+`COM3:57600`) | `/path/log.tlog` (offline replay).
+
+> Set it in the environment, **not** in the server's `environment` block: Hydron spawns local
+> MCP servers with `{...process.env, ...environment}`, so a server-level entry *shadows* your
+> export rather than acting as a default. That is why the plugin sets neither.
 
 > **"Connected" ≠ a live vehicle.** The panel shows `mavlink Connected` once the bridge *process*
 > starts. The tools only return data while something is **actually publishing MAVLink** at the
 > connect target. With no source, calls return empty / time out (`-32001`). Start your SITL/vehicle
 > (or leave it — log analysis via `uav_analyze` doesn't need the live bridge).
 
-> **Param writes are OFF by default.** The bridge defaults to `--read-only`. To enable the
-> tune→push→retest write tier (`param_set` / `param_set_batch`), the command must pass **both**
-> `--no-read-only` **and** `--allow-param-write`:
-> ```jsonc
-> "command": ["python3", "<plugin-path>/bridge/uav_mavlink_bridge.py",
->             "--connect", "udp:127.0.0.1:14550",
->             "--no-read-only", "--allow-param-write"]
+> **⚠ Param writes are ON by default.** The shipped command passes `--no-read-only`
+> `--allow-param-write`, which registers the tune→push→retest write tier (`param_set` /
+> `param_set_batch`). This lets the agent **write parameters to a live vehicle**. Prefer
+> SITL/bench, and point `MAVLINK_CONNECT` at a real airframe only when you intend that.
+>
+> To ship read-only, remove both flags from the `config` hook in `src/index.ts` — the bridge's own defaults are
+> `read_only=True` / `allow_param_write=False`, and the write tools are then never registered:
+> ```ts
+> command: [...py, script],   // no --no-read-only / --allow-param-write
 > ```
-> ⚠ this lets the agent **write parameters to a live vehicle** — prefer SITL/bench, and point
-> `--connect` at a real airframe only when you intend that.
+> Reads (`param_get`, `param_get_all`, `read_params`, telemetry) are unaffected either way.
 
 ---
 

package/bridge/requirements.txt

@@ -1,2 +1,6 @@
 pymavlink>=2.4.49
-mcp[cli]>=1.0.0
+# Pinned below 2.0: the MCP Python SDK removed `mcp.server.fastmcp` in 2.x (FastMCP is gone,
+# replaced by a different MCPServer API), so this bridge fails at import on mcp>=2. The
+# unpinned `>=1.0.0` silently floated into that breaking major. Porting to the 2.x server API
+# is a separate change; until then this range is the supported one (verified on 1.29.0).
+mcp[cli]>=1.0.0,<2

package/mcp.json

@@ -4,12 +4,6 @@
     "url": "https://mcp.exa.ai/mcp",
     "headers": { "x-api-key": "${EXA_API_KEY}" },
     "enabled": false
-  },
-  "mavlink": {
-    "type": "local",
-    "enabled": false,
-    "command": ["python3", "./bridge/uav_mavlink_bridge.py", "--connect", "udp:127.0.0.1:14550"],
-    "environment": { "MAVLINK_DIALECT": "ardupilotmega" },
-    "timeout": 10000
   }
 }
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@h2loop/uav",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "UAV domain pack for Hydron — ArduPilot/PX4 flight-log intelligence (analyze, triage, compare, tune)",
   "type": "module",
   "private": false,